home *** CD-ROM | disk | FTP | other *** search
/ Merciful 2 / Merciful - Disc 2.iso / software / i / imagefxv2.1a.lha / ImageFX / MAGIC / doc / magic.autodoc
Text File  |  1996-02-12  |  35KB  |  1,094 lines
  1. TABLE OF CONTENTS
  2.  
  3. magic.library/--background--
  4. magic.library/--messages--
  5. magic.library/AddMagicImage
  6. magic.library/AllocMagicImageA
  7. magic.library/AttemptLockMagicImage
  8. magic.library/CloseMagicImage
  9. magic.library/CycleMagicImage
  10. magic.library/FreeMagicImage
  11. magic.library/GetMagicImageDataA
  12. magic.library/IsMagicMessage
  13. magic.library/LockMagicImage
  14. magic.library/OpenMagicImageA
  15. magic.library/PickMagicImageA
  16. magic.library/PutMagicImageDataA
  17. magic.library/RedrawMagicImage
  18. magic.library/RemMagicImage
  19. magic.library/RestoreMagicImage
  20. magic.library/SaveMagicImage
  21. magic.library/SetDefaultMagicImage
  22. magic.library/UnlockMagicImage
  23. magic.library/UpdateMagicImage
  24.  
  25.  
  26.  
  27. magic.library/--background--                     magic.library/--background--
  28.  
  29.     - What is MAGIC?
  30.  
  31.     MAGIC is a purely marketing-inspired name for a system of sharing 24-bit
  32.     image data between MAGIC-aware applications.
  33.  
  34.     - Why is this needed?
  35.  
  36.     The primary reason is to make things easier on the user.  It is very
  37.     awkward to have to save an image out of one program, then run a different
  38.     program and then re-load the image to work on it again.  MAGIC allows the
  39.     image data to be "shared" between the two applications _while they are
  40.     running_.
  41.  
  42.     - What's wrong with the clipboard or HotLinks?
  43.  
  44.     MAGIC is specifically oriented towards 24-bit image data (although it is
  45.     certainly extensible to other types of data, but that is beyond the scope
  46.     of this document).  MAGIC is also an "in-memory" system, where the image
  47.     data is kept in memory instead of on disk.  MAGIC is also very transparent
  48.     to the user; there is no need to "publish" or "subscribe".
  49.  
  50.     - How's it work?
  51.  
  52.     The first step is to run a server program that can be run in the
  53.     background to manage MAGIC images and provide a convenient function
  54.     library.  This server program can be placed in a user's WBStartup
  55.     drawer (if they're running 1.3, user's deserve the associated hassles).
  56.  
  57.     When an application wishes to make an image "public" (available to other
  58.     MAGIC-aware applications), he opens the server-created library (called
  59.     "magic.library") and goes through the steps of creating a MAGIC image.
  60.     The image is then added to the public image list and may from then on be
  61.     "opened" by any other application.
  62.  
  63.     The application that creates a MAGIC image and makes it public is known
  64.     throughout this document as the "owner" of an image.  Those applications
  65.     that open a MAGIC image for use are known as "openers" (creative, huh? :).
  66.  
  67.     - How about all those different image data organizations?
  68.  
  69.     This was a major obstacle in the MAGIC system; everyone seems to have a
  70.     different way of storing image data (there's nothing wrong with this, it
  71.     just makes sharing data a little tough).  MAGIC overcomes this like this:
  72.  
  73.     The owner of an image determines the image data organization (the "native"
  74.     organization).  Since the openers may be expecting a different
  75.     organization, translation functions are provided which allow the opener to
  76.     translate the image data into a known format.  This incurs a bit of a
  77.     speed penalty when processing the image, but this seemed the most logical
  78.     way of approaching the problem.
  79.  
  80.     If the owner of an image is using seperate contiguous blocks for the RGB
  81.     data, it may optionally provide this information so that other
  82.     applications that can handle this organization may use the pointers
  83.     directly.  This seems to be the most popular image data organization, and
  84.     is currently in use by several Amiga products.
  85.  
  86.     - Is it easy to support?
  87.  
  88.     One of the goals was to make the task of integrating MAGIC into existing
  89.     applications fairly painless.  True, some work will be required, but we
  90.     think the benefits are well worth it.
  91.  
  92.     - Does MAGIC cost anything?
  93.  
  94.     No.  The server program and documentation for creating MAGIC-aware
  95.     applications will be freely distributable.
  96.  
  97.     - Are there any gotchas?
  98.  
  99.     Your application must be able to support multi-tasking access to
  100.     your image data, because more than one application may be updating
  101.     their displays based on your image data.  In most cases where the
  102.     image data is stored in memory, this will not be a problem.
  103.  
  104.     - Well, you convinced me.  I'll start supporting it right away!
  105.  
  106.     Cool beans. :)
  107.  
  108.     - Is there anything else I should know?
  109.  
  110.     Yeah, too many questions can get on a person's nerves.
  111.  
  112.     - Sorry.
  113.  
  114.     No problem.
  115.  
  116.  
  117. magic.library/--messages--                         magic.library/--messages--
  118.  
  119.     The following types of messages may be sent to your application
  120.     from MAGIC:
  121.  
  122.         MMSG_CLOSE
  123.  
  124.             This is a request for you to close your handle on a
  125.             particular MAGIC image, as someone else is trying to
  126.             release the image.
  127.  
  128.         MMSG_TOFRONT
  129.  
  130.             This is a request to bring your application's interface
  131.             to the front and activate it.
  132.  
  133.         MMSG_REDRAW
  134.  
  135.             This is a request to redraw some or all of a MAGIC
  136.             image's display.
  137.  
  138.         MMSG_UPDATE
  139.  
  140.             This is sent when the physical dimensions of a MAGIC
  141.             image are being changed.  (NOTE:  This version of MAGIC
  142.             does not yet handle physically changing the size of images
  143.             very well.)
  144.  
  145.         MMSG_SAVEUNDO
  146.  
  147.             Request the owner of a MAGIC image to save a copy of some
  148.             or all of the image in an "undo" buffer, presumably before
  149.             some action is done to the image.
  150.  
  151.         MMSG_RESTOREUNDO
  152.  
  153.             Request the owner of a MAGIC image to undo the last changes
  154.             to a MAGIC image.
  155.  
  156.  
  157. magic.library/AddMagicImage                       magic.library/AddMagicImage
  158.  
  159.     NAME
  160.         AddMagicImage -- Make a MAGIC image available to other tasks.
  161.  
  162.     SYNOPSIS
  163.         success = AddMagicImage ( image );
  164.         D0.L                      A0
  165.  
  166.         BOOL AddMagicImage ( struct MagicImage * );
  167.  
  168.     FUNCTION
  169.         Make a previously allocated and initialized MagicImage structure
  170.         available for other applications to open and access.  Only the
  171.         owner of an image should make it public.
  172.  
  173.     INPUTS
  174.         image -- a pointer to an initialized MagicImage structure,
  175.             which should only be allocated with the AllocMagicImageA()
  176.             function.
  177.  
  178.     RESULTS
  179.         success -- TRUE if the image was successfully added, or FALSE on
  180.             failure.
  181.  
  182.     EXAMPLE
  183.  
  184.     NOTES
  185.  
  186.     BUGS
  187.  
  188.     SEE ALSO
  189.  
  190.  
  191. magic.library/AllocMagicImageA                 magic.library/AllocMagicImageA
  192.  
  193.     NAME
  194.         AllocMagicImageA -- Allocate and initialize a MagicImage structure.
  195.         AllocMagicImage -- varargs stub for AllocMagicImageA().
  196.  
  197.     SYNOPSIS
  198.         image = AllocMagicImageA ( taglist );
  199.         D0.L                       A0
  200.  
  201.         struct MagicImage *AllocMagicImageA ( struct TagItem * );
  202.  
  203.         image = AllocMagicImage ( firstTag, ... );
  204.  
  205.         struct MagicImage *AllocMagicImage ( Tag, ... );
  206.  
  207.     FUNCTION
  208.         Allocate and initialize a new MagicImage structure.  You *must*
  209.         use this function to create the structure to be upwardly compatible.
  210.  
  211.     INPUTS
  212.         taglist -- tags used to initialize the PublicImage structure.
  213.  
  214.                 AMI_Width:
  215.                     (LONG) Width of image data in pixels.
  216.  
  217.                 AMI_Height:
  218.                     (LONG) Height of image data in pixels.
  219.  
  220.                 AMI_Depth:
  221.                     (LONG) Depth of image data in 8-bit planes (eg. 1 for an
  222.                     8-bit greyscale image or 3 for a 24-bit RGB color
  223.                     image).
  224.  
  225.                 AMI_Name:
  226.                     (char *) Name of the public image buffer.  Defaults to a
  227.                     unique name.
  228.  
  229.                 AMI_ImageData:
  230.                     (APTR) Information need by the owner of this image to
  231.                     decipher it's contents.  Could be nothing more than a
  232.                     pointer to an array of RGB plane pointers.
  233.  
  234.                 AMI_GetDataCode:
  235.                     (int (*)()) Hook function to convert the native format
  236.                     of this image buffer into lines of RGB data.  The
  237.                     function will fail if this tag is not given.
  238.  
  239.                 AMI_PutDataCode:
  240.                     (int (*)()) Hook function to store lines of RGB data
  241.                     into this image buffer, converting to its native
  242.                     format as necessary.  The function will fail if this
  243.                     tag is not given.
  244.  
  245.                 AMI_Red:
  246.                     (UBYTE *) Pointer to contiguous block of chunky red
  247.                     image data, if you are able to provide this information.
  248.                     If not specified, an application will be forced to go
  249.                     through a translation process to get to your image data.
  250.  
  251.                 AMI_Green:
  252.                     (UBYTE *) Pointer to contiguous block of chunky green
  253.                     image data, if you are able to provide this information.
  254.  
  255.                 AMI_Blue:
  256.                     (UBYTE *) Pointer to contiguous block of chunky blue
  257.                     image data, if you are able to provide this information.
  258.  
  259.                 AMI_Alpha:
  260.                     (UBYTE *) Pointer to contiguous block of chunky 8-bit
  261.                     alpha channel data, if you are able to provide this
  262.                     information.
  263.  
  264.                 AMI_AspectX:
  265.                     (LONG) Horizontal pixel aspect ratio of the new image.
  266.                     Defaults to 1.
  267.  
  268.                 AMI_AspectY:
  269.                     (LONG) Vertical pixel aspect ratio of the new image.
  270.                     Defaults to 1.
  271.  
  272.                 AMI_DPIX:
  273.                     (LONG) Horizontal pixels per inch of the new image.
  274.                     Defaults to 300.
  275.  
  276.                 AMI_DPIY:
  277.                     (LONG) Vertical pixels per inch of the new image.
  278.                     Defaults to 300.
  279.  
  280.                 AMI_OwnerName:
  281.                     (char *) Provide the name of the application that
  282.                     created this image.  Other applications can use
  283.                     this information.  Defaults to NULL, meaning the
  284.                     owner will remain anonymous.
  285.  
  286.     RESULTS
  287.         image -- pointer to MagicImage structure.
  288.  
  289.     EXAMPLE
  290.  
  291.     NOTES
  292.         The TAG_SKIP and TAG_MORE tags are not supported.
  293.  
  294.     BUGS
  295.  
  296.     SEE ALSO
  297.  
  298.  
  299. magic.library/AttemptLockMagicImage       magic.library/AttemptLockMagicImage
  300.  
  301.     NAME
  302.         AttemptLockMagicImage -- Attempt to obtain a lock on a MAGIC image.
  303.  
  304.     SYNOPSIS
  305.         success = AttemptLockMagicImage ( magicHandle, type );
  306.         D0.L                              A0           D0.L
  307.  
  308.         BOOL AttemptLockMagicImage ( struct MagicHandle *, LONG );
  309.  
  310.     FUNCTION
  311.         Attempt to get a read or write lock on the specified public image.  You
  312.         should always obtain a write lock before attempting to modify a
  313.         public image, so two tasks will not try to modify an image at
  314.         the same time.
  315.  
  316.         If the image is write locked by another task, this function will fail
  317.         immediately.  Use LockMagicImage() if you want to wait for the image
  318.         to become available.
  319.  
  320.     INPUTS
  321.         magicHandle -- pointer to a valid image handle as obtained from
  322.             OpenPublicImageA().
  323.  
  324.         type -- type of lock to obtain, LMI_Read or LMI_Write.
  325.  
  326.     RESULTS
  327.         success -- TRUE if the lock was obtained, FALSE on failure.
  328.  
  329.     EXAMPLE
  330.  
  331.     NOTES
  332.  
  333.     BUGS
  334.  
  335.     SEE ALSO
  336.  
  337.  
  338. magic.library/CloseMagicImage                   magic.library/CloseMagicImage
  339.  
  340.     NAME
  341.         CloseMagicImage -- Close a public MAGIC image.
  342.  
  343.     SYNOPSIS
  344.         success = CloseMagicImage ( magicHandle );
  345.         D0.L                        A0
  346.  
  347.         BOOL CloseMagicImage ( struct MagicImage * );
  348.  
  349.     FUNCTION
  350.         Close a previously opened public image, freeing it to be removed
  351.         by its owner.
  352.  
  353.     INPUTS
  354.         magicHandle -- pointer to a valid image handle as obtained from
  355.             OpenMagicImageA().
  356.  
  357.     RESULTS
  358.         success -- TRUE if successful, FALSE on failure.
  359.  
  360.     EXAMPLE
  361.  
  362.     NOTES
  363.  
  364.     BUGS
  365.  
  366.     SEE ALSO
  367.  
  368.  
  369.  
  370. magic.library/CycleMagicImage                   magic.library/CycleMagicImage
  371.  
  372.     NAME
  373.         CycleMagicImage -- Cycle to next application using a MAGIC image.
  374.  
  375.     SYNOPSIS
  376.         CycleMagicImage ( magicHandle );
  377.                           A0
  378.  
  379.         void CycleMagicImage ( struct MagicHandle * );
  380.  
  381.     FUNCTION
  382.         Bring the interface of the next application that has access to the
  383.         given image to the front.  This can be used as a convenience to the
  384.         user when switching between applications.
  385.  
  386.         This function is asynchronous, meaning it returns immediately.
  387.  
  388.         This works by sending a MMSG_TOFRONT message to the next application
  389.         in line that has opened the image.
  390.  
  391.     INPUTS
  392.         magicHandle -- pointer to a valid image handle as obtained from
  393.             OpenMagicImageA().
  394.  
  395.     RESULTS
  396.         None.
  397.  
  398.     EXAMPLE
  399.  
  400.     NOTES
  401.  
  402.     BUGS
  403.  
  404.     SEE ALSO
  405.  
  406.  
  407. magic.library/FreeMagicImage                     magic.library/FreeMagicImage
  408.  
  409.     NAME
  410.         FreeMagicImage -- Free a MAGIC image structure.
  411.  
  412.     SYNOPSIS
  413.         FreeMagicImage ( magicImage );
  414.                          A0
  415.  
  416.         void FreeMagicImage ( struct MagicImage * );
  417.  
  418.     FUNCTION
  419.         Frees all memory associated with a MagicImage structure.  This call
  420.         must only be used on MagicImage's created with the AllocMagicImageA()
  421.         function.
  422.  
  423.     INPUTS
  424.         magicImage -- pointer to a MagicImage structure to free.
  425.  
  426.     RESULTS
  427.         None.
  428.  
  429.     EXAMPLE
  430.  
  431.     NOTES
  432.         This function does not check to see if anyone has opened the image in
  433.         question; only the owner of an image should free the associated
  434.         MagicImage structure when everyone has closed it.
  435.  
  436.     BUGS
  437.  
  438.     SEE ALSO
  439.  
  440.  
  441. magic.library/GetMagicImageDataA             magic.library/GetMagicImageDataA
  442.  
  443.     NAME
  444.         GetMagicImageDataA -- Retreive rows of image data.
  445.         GetMagicImageData -- varargs stub to GetMagicImageDataA.
  446.  
  447.     SYNOPSIS
  448.         success = GetMagicImageDataA ( magicHandle, yoffset, rows, tagList );
  449.         D0.L                           A0           D0.L     D1.L  A1
  450.  
  451.         BOOL GetMagicImageDataA ( struct MagicHandle *, LONG, LONG,
  452.                                   struct TagItem * );
  453.  
  454.         success = GetMagicImageData ( magicHandle, yoffset, rows, ... );
  455.  
  456.         BOOL GetMagicImageData ( struct MagicHandle *, LONG, LONG, ... );
  457.  
  458.     FUNCTION
  459.         Copies image data from the given MAGIC image into caller-supplied
  460.         buffers, calling the image's translation function (set by the owner of
  461.         the image).
  462.  
  463.     INPUTS
  464.         magicHandle -- pointer to a valid image handle as obtained from
  465.             OpenPublicImageA().
  466.  
  467.         yoffset -- topmost row to start copying from, starting from 0.
  468.  
  469.         rows -- number of rows of image data to copy.
  470.  
  471.         tagList -- tags describing the image data to get:
  472.  
  473.                 GMI_Red:
  474.                     (UBYTE *) Copies red image data into the caller's buffer,
  475.                     1 byte per pixel.  If the image buffer is greyscale, the
  476.                     greyscale data will be copied.
  477.  
  478.                 GMI_Green:
  479.                     (UBYTE *) Copies green image data into the caller's
  480.                     buffer, 1 byte per pixel.
  481.  
  482.                 GMI_Blue:
  483.                     (UBYTE *) Copies blue image data into the caller's buffer,
  484.                     1 byte per pixel.
  485.  
  486.                 GMI_RGB:
  487.                     (UBYTE *) Copies RGB imgae data into the caller's buffer,
  488.                     3 bytes per pixel in the format RGBRGBRGB...
  489.  
  490.                 GMI_ARGB:
  491.                     (UBYTE *) Copies RGB image data + alpha channel
  492.                     information into the caller's buffer, 4 bytes per pixel in
  493.                     the format ARGBARGBARGB...
  494.  
  495.                 GMI_RGBA:   (V38)
  496.                     (UBYTE *) Copies RGB image data + alpha channel
  497.                     information into the caller's buffer, 4 bytes per pixel in
  498.                     the format RGBARGBARGBA...
  499.  
  500.                 GMI_Alpha:
  501.                     (UBYTE *) Copies alpha channel information into the
  502.                     caller's buffer, 1 byte per pixel.
  503.  
  504.     RESULTS
  505.         success -- TRUE if all data was succesfully copied, or FALSE if
  506.             something failed (eg. an unrecognized tag was found).
  507.  
  508.     EXAMPLE
  509.  
  510.     NOTES
  511.         You should always obtain a read lock before reading image data!
  512.  
  513.     BUGS
  514.  
  515.     SEE ALSO
  516.  
  517.  
  518. magic.library/IsMagicMessage                     magic.library/IsMagicMessage
  519.  
  520.     NAME
  521.         IsMagicMessage -- Validate a MagicMessage.
  522.  
  523.     SYNOPSIS
  524.         success = IsMagicMessage ( message );
  525.         D0.L                       A0
  526.  
  527.         BOOL IsMagicMessage ( struct Message * );
  528.  
  529.     FUNCTION
  530.         Check to see if the given message structure is actually a
  531.         MagicMessage.  This may be used when you are receiving several message
  532.         types from different sources at the same message port.
  533.  
  534.     INPUTS
  535.         message -- pointer to a Message to check.
  536.  
  537.     RESULTS
  538.         success -- TRUE if the message is a MagicMessage, FALSE if it is not.
  539.  
  540.     EXAMPLE
  541.  
  542.     NOTES
  543.  
  544.     BUGS
  545.  
  546.     SEE ALSO
  547.  
  548.  
  549. magic.library/LockMagicImage                     magic.library/LockMagicImage
  550.  
  551.     NAME
  552.         LockMagicImage -- Obtain a lock on a public MAGIC image.
  553.  
  554.     SYNOPSIS
  555.         success = LockMagicImage ( magicHandle, type );
  556.         D0.L                       A0           D0.L
  557.  
  558.         BOOL LockMagicImage ( struct MagicHandle *, LONG );
  559.  
  560.     FUNCTION
  561.         Obtain a read or write lock on the specified public image.  You should
  562.         always get a write lock before attempting to modify a public, so that
  563.         two tasks will not try to modify an image at the same time.  It is also
  564.         important to obtain a read lock before examining image data.
  565.  
  566.         If the specified image is not available to be locked, this function will
  567.         wait until it becomes available.
  568.  
  569.     INPUTS
  570.         magicHandle -- pointer to a valid image handle as obtained from
  571.             OpenPublicImageA().
  572.  
  573.         type -- type of lock to obtain, LMI_Read or LMI_Write.
  574.  
  575.     RESULTS
  576.         success -- TRUE if the lock was obtained, or FALSE on failure.  The
  577.             function can only fail by supplying an invalid lock type.
  578.  
  579.     EXAMPLE
  580.  
  581.     NOTES
  582.  
  583.     BUGS
  584.  
  585.     SEE ALSO
  586.  
  587.  
  588. magic.library/OpenMagicImageA                   magic.library/OpenMagicImageA
  589.  
  590.     NAME
  591.         OpenMagicImageA -- Obtain access to a public MAGIC image.
  592.         OpenMagicImage -- varargs stub to OpenMagicImageA().
  593.  
  594.     SYNOPSIS
  595.         magicHandle = OpenMagicImageA ( magicImage, name, tagList );
  596.         D0.L                            A0          A1    A2
  597.  
  598.         struct MagicHandle *OpenMagicImageA ( struct MagicImage *,
  599.                                               char *, struct TagItem * );
  600.  
  601.         magicHandle = OpenMagicImage ( magicImage, name, ... );
  602.  
  603.         struct MagicHandle *OpenMagicImage ( struct MagicImage *,
  604.                                              char *, ... );
  605.  
  606.     FUNCTION
  607.         Attempt to open a public image for use by an application.  Once the
  608.         image is opened, an application may access the image data either
  609.         directly or through translation functions (the application should make
  610.         sure to obtain an appropriate lock before accessing/modifying the
  611.         image data).  The image handle returned is used in many other
  612.         magic.library functions.
  613.  
  614.     INPUTS
  615.         magicImage -- pointer to the MagicImage structure you want to open for
  616.             your use.  If NULL, then the name parameter is used to determine
  617.             the public image you want to open.
  618.  
  619.         name -- pointer to (case sensitive) NUL-terminated name of the public
  620.             image you want to open.  If both the magicImage and name
  621.             parameters are NULL, then the default (or active) public image
  622.             will be returned.
  623.  
  624.         tagList -- tags used in opening the image:
  625.  
  626.                 OMI_MsgPort:
  627.                     (struct MsgPort *) Pointer to a message port which the
  628.                     MagicServer program will use to send you messages
  629.                     concerning this image (such as when to redraw, etc.).
  630.  
  631.                 OMI_OwnerPort:
  632.                     (struct MsgPort *) Only the owner of an image should use
  633.                     this tag.  It is identical to OMI_MsgPort, but when the
  634.                     owner of an image opens it (as it must do like anyone
  635.                     else), it should use this tag instead.
  636.  
  637.     RESULTS
  638.         magicHandle -- image handle used by other magic.library functions, or
  639.             NULL if the image could not be opened for some reason.
  640.  
  641.     EXAMPLE
  642.  
  643.     NOTES
  644.         Note that the owner of an image must also open it (ie. use
  645.         OpenMagicImage after calling AddMagicImage).  This is so the owner
  646.         will receive the same messages everyone else will.
  647.  
  648.     BUGS
  649.  
  650.     SEE ALSO
  651.  
  652.  
  653. magic.library/PickMagicImageA                   magic.library/PickMagicImageA
  654.  
  655.     NAME
  656.         PickMagicImageA -- Select MAGIC image from requester.
  657.         PickMagicImage -- varargs stub to PickMagicImageA.
  658.  
  659.     SYNOPSIS
  660.         magicImage = PickMagicImageA ( screen, tagList );
  661.         D0.L                           A0      A1
  662.  
  663.         struct MagicImage *PickMagicImageA ( struct Screen *,
  664.                                              struct TagItem * );
  665.  
  666.         magicImage = PickMagicImage ( screen, firstTag, ... );
  667.  
  668.         struct MagicImage *PickMagicImage ( struct Screen *, ... );
  669.  
  670.     FUNCTION
  671.         Open a standard requester on the caller's choice of
  672.         screen to allow the user to choose a MAGIC image.
  673.         In the default case, all currently available MAGIC images
  674.         will be shown, but tags may be specified to filter out
  675.         certain images.
  676.  
  677.     INPUTS
  678.         screen -- Screen on which to open, or NULL to open on the default
  679.             public screen (ie. Workbench).  Note that the screen will be
  680.             shifted up to make room for the requester if necessary.
  681.  
  682.         tagList -- Tags controlling the image list:
  683.  
  684.                 PMI_MinWidth:
  685.                     (LONG) Only show images whose width is at least this
  686.                     value.
  687.  
  688.                 PMI_MinHeight:
  689.                     (LONG) Only show images whose height (in pixels) is at
  690.                     least this value.
  691.  
  692.                 PMI_MinDepth:
  693.                     (LONG) Only show images whose depth (in byte planes) is at
  694.                     least this value.  Can be used to filter out 8-bit
  695.                     greyscale images.
  696.  
  697.                 PMI_MaxWidth:
  698.                     (LONG) Only show images whose width (in pixels) is less
  699.                     than this value.
  700.  
  701.                 PMI_MaxHeight:
  702.                     (LONG) Only show images whose height (in pixels) is less
  703.                     than this value.
  704.  
  705.                 PMI_MaxDepth:
  706.                     (LONG) Only show images whose depth (in byte planes) is
  707.                     less than this value.  Can be used to filter out color
  708.                     images.
  709.  
  710.                 PMI_ShowSize:
  711.                     (BOOL) If TRUE, display the sizes of images along with
  712.                     their names.
  713.  
  714.                 PMI_ShowOwner :
  715.                     (BOOL) If TRUE, display the owner of images along with
  716.                     their names.
  717.  
  718.                 PMI_All :
  719.                     (BOOL) If TRUE, show all available images without
  720.                     filtering.
  721.  
  722.                 PMI_ExcludeOwner:
  723.                     (char *) Exclude all images that were created by the given
  724.                     owner.  This can be used to filter out images created by
  725.                     the caller.
  726.  
  727.     RESULTS
  728.         magicImage -- Pointer to MagicImage selected by the user, or NULL if
  729.             the user cancels the operation.  The image must still be opened
  730.             before it can be used.
  731.  
  732.     EXAMPLE
  733.  
  734.     NOTES
  735.         The TAG_SKIP and TAG_MORE tags are not supported.
  736.         This function requires GadTools V37+.
  737.  
  738.     BUGS
  739.  
  740.     SEE ALSO
  741.  
  742.  
  743. magic.library/PutMagicImageDataA             magic.library/PutMagicImageDataA
  744.  
  745.     NAME
  746.         PutMagicImageDataA -- Write pixel data into a public MAGIC image.
  747.         PutMagicImageData -- varargs stub to PutMagicImageDataA.
  748.  
  749.     SYNOPSIS
  750.         success = PutMagicImageDataA ( magicHandle, yoffset, rows, tagList );
  751.         D0.L                           A0           D0.L     D1.L  A1
  752.  
  753.         BOOL PutMagicImageDataA ( struct MagicHandle *, LONG, LONG,
  754.                                   struct TagItem * );
  755.  
  756.         success = PutMagicImageData ( magicHandle, yoffset, rows, ... );
  757.  
  758.         BOOL PutMagicImageData ( struct MagicHandle *, LONG, LONG, ... );
  759.  
  760.     FUNCTION
  761.         Copies image data from the caller-supplied buffers into the given
  762.         MAGIC image, calling the image's translation function (set by the
  763.         owner of the image).
  764.  
  765.     INPUTS
  766.         magicHandle -- pointer to a valid image handle as obtained from
  767.             OpenPublicImageA().
  768.  
  769.         yoffset -- topmost row to start copying from, starting from 0.
  770.  
  771.         rows -- number of rows of image data to copy.
  772.  
  773.         tagList -- tags describing the image data to get:
  774.  
  775.                 GMI_Red:
  776.                     (UBYTE *) Stores red image data, as supplied in the
  777.                     caller's buffer, 1 byte per pixel.
  778.  
  779.                 GMI_Green:
  780.                     (UBYTE *) Stores green image data, as supplied in the
  781.                     caller's buffer, 1 byte per pixel.
  782.  
  783.                 GMI_Blue:
  784.                     (UBYTE *) Stores blue image data as supplied in the
  785.                     caller's buffer, 1 byte per pixel.
  786.  
  787.                 GMI_RGB:
  788.                     (UBYTE *) Stores RGB image data as supplied in the
  789.                     caller's buffer, 3 bytes per pixel in the format
  790.                     RGBRGBRGB...
  791.  
  792.                 GMI_ARGB:
  793.                     (UBYTE *) Stores RGB image data + alpha channel
  794.                     information as supplied in the caller's buffer,
  795.                     4 bytes per pixel in the format ARGBARGBARGB...
  796.  
  797.                 GMI_RGBA:   (V38)
  798.                     (UBYTE *) Stores RGB image data + alpha channel
  799.                     information as supplied in the caller's buffer,
  800.                     4 bytes per pixel in the format RGBARGBARGBA...
  801.  
  802.                 GMI_Alpha:
  803.                     (UBYTE *) Stores alpha channel information as supplied in
  804.                     the caller's buffer, 1 byte per pixel.
  805.  
  806.     RESULTS
  807.         success -- TRUE if all data was succesfully copied, or FALSE if
  808.             something failed (eg. an unrecognized tag was found).
  809.  
  810.     EXAMPLE
  811.  
  812.     NOTES
  813.         You should always obtain a write lock before writing image data!
  814.  
  815.     BUGS
  816.  
  817.     SEE ALSO
  818.  
  819.  
  820. magic.library/RedrawMagicImage                 magic.library/RedrawMagicImage
  821.  
  822.     NAME
  823.         RedrawMagicImage -- Refresh display of MAGIC image.
  824.  
  825.     SYNOPSIS
  826.         RedrawMagicImage ( magicHandle, left, top, width, height );
  827.                            A0           D0.L  D1.L D2.L   D3.L
  828.  
  829.         void RedrawMagicImage (struct MagicHandle *, LONG, LONG, LONG, LONG);
  830.  
  831.     FUNCTION
  832.         Signal all the openers of the given image to refresh their displays of
  833.         the image.  All openers are signalled EXCEPT THE ONE THAT CALLED THIS
  834.         FUNCTION!
  835.  
  836.         This function is asynchronous, meaning it returns immediately.
  837.  
  838.         This works by sending a MMSG_REDRAW to all tasks that have opened this
  839.         image, except the task calling this function.
  840.  
  841.     INPUTS
  842.         magicHandle -- pointer to a valid image handle as obtained from
  843.             OpenMagicImageA().
  844.  
  845.         left, top -- upper left corner of area to redraw, starting from 0,0 in
  846.             the far upper left of the image.
  847.  
  848.         width, height -- size of the area to redraw, in pixels.
  849.  
  850.     RESULTS
  851.         None.
  852.  
  853.     EXAMPLE
  854.  
  855.     NOTES
  856.         Due to possible bottlenecks when redrawing several displays at once,
  857.         an application should lower its priority when redrawing due to a
  858.         MMSG_REDRAW message.
  859.  
  860.     BUGS
  861.  
  862.     SEE ALSO
  863.  
  864.  
  865. magic.library/RemMagicImage                       magic.library/RemMagicImage
  866.  
  867.     NAME
  868.         RemMagicImage -- Remove MAGIC image from public scrutiny.
  869.  
  870.     SYNOPSIS
  871.         success = RemMagicImage ( magicImage );
  872.         D0.L                      A0
  873.  
  874.         BOOL RemMagicImage ( struct MagicImage * );
  875.  
  876.     FUNCTION
  877.         Remove the given MagicImage from the public list of images.  Only the
  878.         owner of an image should use this function.  Once the image is removed
  879.         it may be freed at will.
  880.  
  881.         If other applications still have a handle on this image (ie. they have
  882.         opened it), the magic server will send a MMSG_CLOSE to all the
  883.         applications that have it open so they will release the image.
  884.  
  885.     INPUTS
  886.         magicImage -- pointer to a MagicImage structure to be removed.
  887.  
  888.     RESULTS
  889.         success -- TRUE if the image was removed, or FALSE if the image could
  890.             not be removed for some reason.
  891.  
  892.     EXAMPLE
  893.  
  894.     NOTES
  895.         The owner of an image *MUST* close the image BEFORE calling
  896.         RemMagicImage or a deadlock will occur.
  897.  
  898.     BUGS
  899.  
  900.     SEE ALSO
  901.  
  902.  
  903. magic.library/RestoreMagicImage               magic.library/RestoreMagicImage
  904.  
  905.     NAME
  906.         RestoreMagicImage -- Request owner to restore undo copy of image.
  907.  
  908.     SYNOPSIS
  909.         success = RestoreMagicImage ( magicHandle );
  910.         D0.L                          A0
  911.  
  912.         BOOL RestoreMagicImage ( struct MagicHandle * );
  913.  
  914.     FUNCTION
  915.         Send a request to the owner of a MAGIC image to restore the latest
  916.         undo copy into the image.
  917.  
  918.         The function does not return until the restoration is complete.
  919.  
  920.         This works by sending a MMSG_RESTOREUNDO message to the owner of the
  921.         image.
  922.  
  923.     INPUTS
  924.         magicHandle -- pointer to a valid image handle as obtained from
  925.             OpenMagicImageA().
  926.  
  927.     RESULTS
  928.         success -- TRUE if the copy was successfully restored, or FALSE if
  929.             something went wrong.
  930.  
  931.     EXAMPLE
  932.  
  933.     NOTES
  934.         The owner of an image may choose to ignore the request.
  935.  
  936.         The owner of an image should never call this function, or a deadlock
  937.         will occur.
  938.  
  939.     BUGS
  940.  
  941.     SEE ALSO
  942.  
  943.  
  944. magic.library/SaveMagicImage                     magic.library/SaveMagicImage
  945.  
  946.     NAME
  947.         SaveMagicImage -- Request owner to save an undo copy of image.
  948.  
  949.     SYNOPSIS
  950.         success = SaveMagicImage ( magicHandle, left, top, width, height );
  951.         D0.L                       A0           D0.L  D1.L D2.L   D3.L
  952.  
  953.         BOOL SaveMagicImage ( struct MagicHandle *, LONG, LONG, LONG, LONG );
  954.  
  955.     FUNCTION
  956.         Request the owner of the given MAGIC image to store a copy of the area
  957.         indicated in a temporary "undo" buffer which may be restored later.
  958.         The owner of an image is responsible for making and restoring undo
  959.         copies.
  960.  
  961.         This function does not return until the save is complete.
  962.  
  963.         This works by sending an MMSG_SAVEUNDO message to the owner of an
  964.         image and waiting for a reply.
  965.  
  966.     INPUTS
  967.         magicHandle -- pointer to a valid image handle as obtained from
  968.             OpenMagicImageA().
  969.  
  970.         left, top -- upper left corner of area to save, starting from 0,0 in
  971.             the far upper left of the image.
  972.  
  973.         width, height -- size of the area to save, in pixels.
  974.  
  975.     RESULTS
  976.         success -- TRUE if the undo copy was successfully saved, or FALSE if
  977.             it was not.
  978.  
  979.     EXAMPLE
  980.  
  981.     NOTES
  982.         The owner of an image may choose to ignore the request, or save the
  983.         full area of an image instead of the requested subset.
  984.  
  985.         The owner of an image should never call this function, or a deadlock
  986.         will occur.
  987.  
  988.     BUGS
  989.  
  990.     SEE ALSO
  991.  
  992.  
  993. magic.library/SetDefaultMagicImage         magic.library/SetDefaultMagicImage
  994.  
  995.     NAME
  996.         SetDefaultMagicImage -- Select the "default" MAGIC image.
  997.  
  998.     SYNOPSIS
  999.         success = SetDefaultMagicImage ( magicImage );
  1000.         D0.L                             A0
  1001.  
  1002.         BOOL SetDefaultMagicImage ( struct MagicImage * );
  1003.  
  1004.     FUNCTION
  1005.         Set the "default" image that will be opened when no parameters are
  1006.         given to OpenMagicImageA().  This function is reserved for "MAGIC
  1007.         image manager" type programs, and shouldn't be used arbitrarily.
  1008.  
  1009.     INPUTS
  1010.         magicImage -- pointer to a MagicImage structure as returned by
  1011.             AllocMagicImageA() or obtained through the MagicBase list.
  1012.  
  1013.     RESULTS
  1014.         success -- TRUE if the image was successfully set, or FALSE on
  1015.             failure.
  1016.  
  1017.     EXAMPLE
  1018.  
  1019.     NOTES
  1020.  
  1021.     BUGS
  1022.  
  1023.     SEE ALSO
  1024.  
  1025.  
  1026. magic.library/UnlockMagicImage                 magic.library/UnlockMagicImage
  1027.  
  1028.     NAME
  1029.         UnlockMagicImage -- Release a lock on a public MAGIC image.
  1030.  
  1031.     SYNOPSIS
  1032.         UnlockMagicImage ( magicHandle );
  1033.                            A0
  1034.  
  1035.         void UnlockMagicImage ( struct MagicHandle * );
  1036.  
  1037.     FUNCTION
  1038.         Releases either a read or write lock that you have previously obtained
  1039.         on an image.  The image is then free to be used by others or removed.
  1040.  
  1041.     INPUTS
  1042.         magicHandle -- pointer to a valid image handle as obtained from
  1043.             OpenPublicImageA().
  1044.  
  1045.     RESULTS
  1046.         None.
  1047.  
  1048.     EXAMPLE
  1049.  
  1050.     NOTES
  1051.  
  1052.     BUGS
  1053.  
  1054.     SEE ALSO
  1055.  
  1056.  
  1057. magic.library/UpdateMagicImage                 magic.library/UpdateMagicImage
  1058.  
  1059.     NAME
  1060.         UpdateMagicImage -- Signal image openers of size change.
  1061.  
  1062.     SYNOPSIS
  1063.         UpdateMagicImage ( magicHandle );
  1064.                            A0
  1065.  
  1066.         void UpdateMagicImage ( struct MagicHandle * );
  1067.  
  1068.     FUNCTION
  1069.         Signal all openers of an image that the owner has changed the physical
  1070.         dimensions of the image (eg. width, height, depth).  Only the owner of
  1071.         an image may (safely) change the physical dimensions.
  1072.  
  1073.         This function does not return until all openers have updated.
  1074.  
  1075.         This works by sending a MMSG_UPDATE to all openers of the image
  1076.         (except the one calling this function!).
  1077.  
  1078.     INPUTS
  1079.         magicHandle -- pointer to a valid image handle as obtained from
  1080.             OpenMagicImageA().
  1081.  
  1082.     RESULTS
  1083.         None.
  1084.  
  1085.     EXAMPLE
  1086.  
  1087.     NOTES
  1088.  
  1089.     BUGS
  1090.  
  1091.     SEE ALSO
  1092.  
  1093.  
  1094.